home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.038 < prev    next >
Encoding:
Text File  |  1990-09-21  |  9.4 KB  |  281 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. Apple IIgs
  7. #38:    List Controls in Dialog Boxes
  8.  
  9. Revised by:    C.K. Haun                                       September 1990
  10. Written by:    Keith Rollin, Dave Lyons & Eric Soldan                May 1988
  11.  
  12. This Technical Note describes how to include a list control into a dialog box.  
  13. Sample APW C source code is included.
  14. Changes since March 1990:  Changed input parameter definition for myFilterProc 
  15. from long pointer to word pointer.
  16. _____________________________________________________________________________
  17.  
  18. The need to put a list control into a dialog box is obvious.  The Print 
  19. Manager does it.  The Font Manager does it.  You may want to use one in your 
  20. own application to manage a list of data base fields or spreadsheet functions.  
  21. However, performing the task is not as obvious as the need.
  22.  
  23. Given the features of TaskMaster in System Software 5.0, it is now much easier 
  24. to emulate a modal dialog in a normal window.  If you need to add a list 
  25. control to a modal dialog, you should seriously consider emulating a modal 
  26. dialog with a normal window instead of using the Dialog Manager.  If you use 
  27. the Dialog Manager, the following procedure and sample C fragment illustrate 
  28. the technique necessary for adding a list control.
  29.  
  30. Note that only one list control is allowed in a modal dialog.  If you need 
  31. more than one, the Dialog Manager cannot help you--create a normal window 
  32. instead.
  33.  
  34.  
  35. Individual Steps
  36.  
  37. Basically, there are three check-off items for putting a list control into a 
  38. dialog box:
  39.  
  40.    1.  You must install the list explicitly into the dialog box yourself.  
  41.        This should be done after you have created the dialog box with a 
  42.        call to NewModalDialog or GetNewModalDialog.  Do not install it as 
  43.        a UserItem or UserCtlItem.  Installing it as a UserItem would 
  44.        cause the Dialog Manager to place an invisible custom control over 
  45.        the list, preventing later use of FindControl to manage it.  
  46.        Installing the list as a UserCtlItem does not allow the list 
  47.        control to be properly initialized.
  48.  
  49.        Note:  After you add the list control, you must not add any more 
  50.               dialog items.
  51.  
  52.        InitValues()
  53.        {
  54.            /* Get a Full Screen, invisible dialog window with only
  55.               a Quit button in it*/
  56.            myDialog = GetNewModalDialog(&PrintDialog);
  57.  
  58.  
  59.            /* Add this List Control ourselves */
  60.            myListHndl = CreateList(myDialog,&myList);
  61.  
  62.            /* Get the handle for the Scrollbar Control */
  63.            listScrollHandle = (**myListHndl).ctlListBar;
  64.  
  65.            /* Save and Zero out the RefCons */
  66.            listRefCons = GetCtlRefCon(myListHndl);
  67.            scrollRefCons = GetCtlRefCon(listScrollHandle);
  68.            ZeroRefCons(); /* This is explained below in item #3 */
  69.  
  70.            /* Now show the dialog box */
  71.            ShowWindow(myDialog);
  72.        }
  73.  
  74.    2.  Because the list control is not a dialog item, a custom FilterProc 
  75.        must be installed for ModalDialog to test for mouse-down events.  
  76.        Pass the address of this routine (with the high bit set so that 
  77.        default handling of items is in effect) when you call ModalDialog.
  78.  
  79.        pascal Word myFilterProc(theDialog, theEvent, theItem)
  80.            GrafPortPtr    theDialog;
  81.            EventRecord    *theEvent;
  82.            word           *theItem;
  83.  
  84.        {
  85.            CtlRecHndl  tHandle;
  86.  
  87.            if ((*theEvent).what == mouseDownEvt) {
  88.                FindControl(&tHandle,(*theEvent).where,theDialog);
  89.                if ((tHandle == myListHndl) || (tHandle == listScrollHandle)) {
  90.  
  91.                    /* Set the RefCons back to the way the list manager likes 
  92.                       them */
  93.                    RestoreRefCons();
  94.                    TrackControl((*theEvent).where,(LongProcPtr) -1, tHandle);
  95.                    ZeroRefCons();
  96.  
  97.                    /* Tell the Dialog Manager that we handled this event */
  98.                    return(true);
  99.                }
  100.            }
  101.            /* We didn't do anything, so return false to get Dialog Manager
  102.                to handle this event */
  103.          return(false);
  104.        }
  105.  
  106.    3.  The Dialog Manager uses the RefCon field of its items (all of 
  107.        which are installed as controls).  Unfortunately, the List Manager 
  108.        also uses the RefCon field for its own purposes.  This shared use 
  109.        means that a judicious juggling of those values is required.  This 
  110.        juggling is the reason for the two routines RestoreRefCons and 
  111.        ZeroRefCons used above.
  112.  
  113.        /* Zero out the RefCons for the Dialog Manager */
  114.        ZeroRefCons()
  115.        {
  116.            SetCtlRefCon(0,myListHndl);
  117.            SetCtlRefCon(0,listScrollHandle);
  118.        }
  119.  
  120.  
  121.        /* Restore the RefCons for the List Manager */
  122.        RestoreRefCons()
  123.        {
  124.            SetCtlRefCon(listRefCons,myListHndl);
  125.            SetCtlRefCon(scrollRefCons,listScrollHandle);
  126.        }
  127.  
  128. Note:  Because the Dialog Manager currently uses the RefCon to keep track 
  129.        of which dialog item is identified with which particular control, 
  130.        zeroing the RefCon fields can cause a little confusion.  
  131.        Specifically, those who would like to do GetFirstDItem from within 
  132.        a Standard File call may get a zeroed RefCon as a result.  This is 
  133.        true for Standard File 3.0 and later (System Software 5.0), as 
  134.        this is the first implementation of Standard File to use the List 
  135.        Manager.
  136.  
  137.  
  138. Putting It All Together
  139.  
  140. Here are most of the pieces put together.  InitTools and ShutDownStuff 
  141. routines have been omitted, but they are straightforward.
  142.  
  143. char              **y,*z;
  144. GrafPortPtr       myDialog;
  145. ListCtlRecHndl    myListHndl;
  146. CtlRecHndl        listScrollHandle;
  147. long              listRefCons, scrollRefCons;
  148.  
  149. #define Quit      ok
  150.  
  151. char  quitStr[] = "\pQuit";
  152.  
  153. ItemTemplate quitButton =  {
  154.            Quit,
  155.            140,450,154,590,
  156.            buttonItem,
  157.            quitStr,
  158.            0,
  159.            0,
  160.            NULL};
  161.  
  162. DialogTemplate PrintDialog = {
  163.            30,20,190,620,
  164.            false,
  165.            0,
  166.            &quitButton,
  167.            NULL};
  168.  
  169. char string1[] = "String1";
  170. char string2[] = "String2";
  171. char string3[] = "String3";
  172. char string4[] = "String4";
  173. char string5[] = "String5";
  174. char string6[] = "String6";
  175. char string7[] = "String7";
  176. char string8[] = "String8";
  177.  
  178.  
  179. MemRec  myMembers[8] = {
  180.            string1, 00,
  181.            string2, 00,
  182.            string3, 00,
  183.            string4, 00,
  184.            string5, 00,
  185.            string6, 00,
  186.            string7, 00,
  187.            string8, 00};
  188.  
  189. ListRec  myList = {
  190.            40,175,102,400, /* Enclosing Rectangle */
  191.            8,              /* Number of List Members */
  192.            6,              /* Max Viewable members */
  193.            3,              /* Bit Flag */
  194.            1,              /* First member in view */
  195.            NULL,           /* List control's handle */
  196.            NULL,           /* Address of Custom drawing routine */
  197.            10,             /* Height of list members */
  198.            5,              /* Size of Member Records */
  199.            (MemRecPtr)myMembers,/* Pointer to first element in MemRec[] */
  200.            NULL,           /* Becomes Control's refCon */
  201.            NULL            /* Color table for list's scroll bar */
  202.            };
  203.  
  204. /* ************************** */
  205.  
  206. main()
  207. {
  208.        word what;
  209.  
  210.        InitTools();         /* initialize tools */
  211.        InitValues();        /* Get dialog box. Install List control */
  212.        do {
  213.            what = ModalDialog((WordProcPtr)((long)myFilterProc | 0x80000000)); 
  214.        } while (what != Quit);
  215.        ShutDownStuff();  
  216. }
  217.  
  218. pascal Word myFilterProc(theDialog, theEvent, theItem)
  219.        GrafPortPtr    theDialog;
  220.        EventRecord    *theEvent;
  221.        word           *theItem;
  222.  
  223. {
  224.        CtlRecHndl     tHandle;
  225.  
  226.        if ((*theEvent).what == mouseDownEvt) {
  227.            FindControl(&tHandle,(*theEvent).where,theDialog);
  228.            if ((tHandle == myListHndl) || (tHandle == listScrollHandle)) {
  229.  
  230.                /* Set the RefCons back to the way the list manager 
  231.                   likes them */
  232.                RestoreRefCons();
  233.                TrackControl((*theEvent).where,(LongProcPtr) -1, tHandle);
  234.                ZeroRefCons();
  235.  
  236.                /* Tell the Dialog Manager that we handled this event */
  237.                return(true);
  238.            }
  239.        }
  240.        /* We didn't do anything, so return false to get Dialog Manager
  241.           to handle this event */
  242.   return(false);
  243. }
  244.  
  245.  
  246. /* Zero out the Refcons for the Dialog Manager */
  247. ZeroRefCons()
  248. {
  249.        SetCtlRefCon(0,myListHndl);
  250.        SetCtlRefCon(0,listScrollHandle);
  251. }
  252.  
  253. /* Restore the Refcons for the List Manager */
  254. RestoreRefCons()
  255. {
  256.        SetCtlRefCon(listRefCons,myListHndl);
  257.        SetCtlRefCon(scrollRefCons,listScrollHandle);
  258. }
  259.  
  260. InitValues()
  261. {
  262.        /* Get a Full Screen, invisible dialog window with only a Quit button 
  263.           in it*/
  264.        myDialog = GetNewModalDialog(&PrintDialog);
  265.  
  266.        /* Add this List Control ourselves */
  267.        myListHndl = CreateList(myDialog,&myList);
  268.  
  269.        /* Get the handle for the Scrollbar Control */
  270.        listScrollHandle = (**myListHndl).ctlListBar;
  271.  
  272.        /* Save and Zero out the RefCons */
  273.        listRefCons = GetCtlRefCon(myListHndl);
  274.        scrollRefCons = GetCtlRefCon(listScrollHandle);
  275.        ZeroRefCons();
  276.  
  277.        /* Now show the dialog box */
  278.        ShowWindow(myDialog);
  279. }
  280.  
  281.